home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / web / fweb / READ_ME-1.40 < prev   
Text File  |  1993-12-02  |  9KB  |  189 lines
  1.                  FWEB version 1.40
  2.                  October 30, 1993
  3.  
  4.   FWEB v1.40, such as it is, is available from
  5.  
  6.     ftp.pppl.gov:/pub/fweb/fweb-1.40.tar.Z
  7.  
  8. It contains some bug fixes and various new features, described below.
  9. However, because this version initiates some major upgrades and has been
  10. inadequately debugged, it is NOT RECOMMENDED for new users or for large
  11. programming projects already dependent on a stable FWEB environment.  It is
  12. my hope that some experts will play with this version and report their
  13. difficulties, so that a stable version will evolve.
  14.  
  15.   The major points are:
  16.  
  17.     * Documentation standardized on gnu texinfo;
  18.  
  19.     * Full LaTeX support;
  20.  
  21.     * Verbatim `language' and language-independent mode.
  22.  
  23.  
  24.                   MAJOR FEATURES
  25.  
  26. * Documentation current with v1.40 is now written in texinfo format.  The
  27. fweb.texinfo document is not yet as complete as the old fwebman.tex (which
  28. is still supplied, but is frozen at v1.30).  However, it is now usefully
  29. TeXable, and the on-line document fweb.info (accessible through emacs' info
  30. browser) is reasonably extensive.  For a summary of the features new with
  31. version 1.40, see the info menu item `New features'.
  32.  
  33.  
  34. * Previous versions of FWEB did not work entirely gracefully with LaTeX, in
  35. that LaTeX's \output routine was usurped by FWEB.  That is no longer the
  36. case; LaTeX's \output routine is now used, as are its sectioning and
  37. table-of-contents commands.  Things like footnotes should now work.
  38.  
  39.   The new LaTeX support necessitated major changes to FWEB's macro package
  40. fwebmac.web.  An attempt has been made to provide a seamless transition
  41. from previous versions, as follows.  Two macro packages are now provided:
  42.  
  43.     fwebmac.sty --- The old v1.30 one, with minimal modifications
  44.             required for v1.40.
  45.  
  46.     fwebmacL.sty --- The new macros.
  47.  
  48. By default, FWEB looks for fwebmac.sty.  In order to force FWEB to use the
  49. new macros, you should put into your initialization file .fweb the line
  50.  
  51.     +wfwebmacL.sty
  52.  
  53. This package is supposed to work with TeX as well as LaTeX.  In principle,
  54. the old and new macros should work the same when using TeX.  However, when
  55. using LaTeX with the new ones, the appearance of FWEAVE's output will be
  56. noticably  different.  In particular, it is supposed to look more
  57. `book-like' in appearance.  Sections are no longer numbered at the
  58. beginning of the TeX part, but rather when the code part (if any) begins.
  59. Section numbering will be LaTeX's---e.g., 13.1.5, and this will be
  60. reflected in the index and other cross-reference information.  The scheme
  61. uses ideas recently discussed in comp.programming.literate, but feedback is
  62. very desirable.  Remember, if you don't like the new look, you can for the
  63. time being use TeX instead of LaTeX.  I encourage you to use LaTeX, but if
  64. you do, you're stuck with the new look.
  65.  
  66.   There are several difficulties with the new LaTeX support: 
  67.  
  68. (1) Macro expansion in section titles may not work with latex
  69. and/or nlatex.  This includes constructions like ``@* {\tt TITLE}.'' and
  70. ``@* |function|.''  Some \protect's need to be scattered around.  I'll get
  71. to this eventually.
  72.  
  73. (2) Another unusual behavior is that after an editing change LaTeX
  74. may not warn that section numbering is out of date.  If in doubt, or if
  75. question marks appear in place of section numbers, rerun latex.
  76.  
  77. (3) Finally, the last section of your document should begin
  78.  
  79.     @* INDEX.
  80.  
  81. where ``INDEX'' is in upper case.  This case convention is a kludge (to
  82. force a shift into two-column output) that will be fixed someday.
  83.  
  84. * This version features the beginnings of some work on language
  85. independence.  In principle, it is now possible to weave and tangle
  86. sections of code literally (verbatim) instead of using FWEAVE's
  87. pretty-printing and FTANGLE's blank suppression.  One is supposed to be
  88. able to do this both for compiler languages like Fortran or C that FWEAVE
  89. can pretty-print, as well as for any other language (makefiles, etc.) whose
  90. syntax FWEB does not understand.  It is certain that these features have
  91. not yet been fully or entirely correctly implemented.  The general mechanism is
  92. complex, as it must interact smoothly with FTANGLE's macro preprocessor and
  93. other such features.  I STRONGLY RECOMMEND THAT NOBODY BEGIN A LARGE-SCALE
  94. PROGRAMMING PROJECT USING THESE NEW LANGUAGE-INDEPENDENT FEATURES.  That
  95. said, I hope people will try it out so problems can be identified and
  96. fixed.
  97.  
  98.   There are two ways of obtaining language independence: a
  99. language-independent `mode' (the `N mode') that can be used even for
  100. languages such as Fortran, and a `verbatim language'.  The verbatim
  101. language is the stronger of the two; it turns on the language-independent
  102. mode.  The two concepts are closely related, and in some applications they
  103. will function identically.
  104.     
  105.   If you are, say, a Fortran programmer but merely want to turn off
  106. pretty-printing, you should use the N mode.  This is done by using the
  107. command-line option `-N'.  (Case is significant; `-n' means something
  108. entirely different.)  FWEAVE will just print your source in a verbatim
  109. environment, and will continue to do indexing as usual; FTANGLE will copy
  110. the source literally to the output file, say test.f.
  111.  
  112.   If you are using FWEB to document a language different than the supported
  113. ones of C, C++, Fortran, Ratfor, and TeX, then you should select the
  114. verbatim language by means of the language command `@Lv' (replacing
  115. something like `@c', `@n', or `@Lx').  FWEAVE will again print your source
  116. in a verbatim environment, and FTANGLE will copy it to the output file
  117. test.mk.  (The `.mk' extension can be changed in the style file.)
  118.  
  119.   The N mode and the verbatim language are supposed to obey the usual
  120. scoping and inheritance rules (modules inherit the features of their
  121. ancestors), so that mixed-language programming still works correctly.
  122. There are probably some difficulties here, however.
  123.  
  124.   Cross-referencing is turned off under `@Lv'.  However, FWEAVE still
  125. recognizes identifiers according to FWEB's rules.  This does not always
  126. make sense, and in the future a mechanism should be provided for modifying
  127. those rules.  (This is tricky because of built-in functions, WEB macros,
  128. etc.)  In any event, an index entry for FWEB's current understanding of an
  129. identifier can be forced by means of the `@+' command.
  130.  
  131.   Sharp-eyed users will note that `@+' used to mean something
  132. else---namely, it prevented a line break, as in `x; @+ y;'.  That role is
  133. now played by `@~' (which, if you think of TeX, should be easier to
  134. remember).  I regret making this change, but the new usage is now symmetric
  135. with the `@-' command, which means delete an index entry.  Incidently,
  136. another change that was made in the last version, namely replacing the
  137. compiler directive command `@!' by `@?', now becomes more crucial since
  138. `@!' is now used to suppress expansion of a WEB macro or built-in function.
  139. (This is sometimes particular necessary in the language-independent modes.)
  140. In summary, five important control codes in the current version are
  141.  
  142.     @? --- compiler directive
  143.     @~ --- suppress line break
  144.     @! --- suppress macro expansion of next identifier
  145.     @- --- suppress index entry for next identifier
  146.     @+ --- force index entry for next identifier
  147.  
  148. If you are unwilling to convert old codes and will not be using
  149. language-independent features, it is possible to restore the old meaning of
  150. `@+'; see `New features' of fweb.info.  However, I don't recommend this; it
  151. will just cause confusion later.  
  152.  
  153.  
  154.              RELATIVELY MINOR CHANGES
  155.  
  156. * Built-in functions now begin with '$', not '_'.  For example, you should
  157. say `$EVAL(1+2)', not `_EVAL(1+2)'.  The underscore convention was a poor
  158. design decision that introduced conflicts with ANSI C in certain cases.
  159. Existing codes will continue to work, as FWEB now understands both
  160. conventions.  One can therefore say things like `@#undef _EVAL' (retaining
  161. the functionality of $EVAL), but the underscore convention may go away in
  162. some future release.
  163.  
  164. * When the `-F' option is used, FTANGLE will write its output to temporary
  165. files and compare the results to the last version in the directory, if any.
  166. The file is updated only if a difference is found.  This prevents make
  167. files from recompiling source if only the documentation was changed.  This
  168. feature was not entirely trivial to make portable, so please report any
  169. difficulties. 
  170.  
  171. * A new flag `-n)' (reverse Fortran indices) has been added.  This may be
  172. very useful for advanced Fortran programming; see fweb.info for its
  173. description. 
  174.  
  175. * The ./configure automatic configuration script has been improved, and should
  176. lead to easy installation on many systems.  Please report any difficulties
  177. you have with using this script.
  178.  
  179. * The following change will be completely invisible to the user (provided
  180. it works correctly), but effects a dramatic simplification for the code
  181. development: the large typedefs.hweb, containing many #defines, is no
  182. longer included into every FWEB source file.  Rather, the #defines are
  183. localized into a typedefs.h that is #included into the C source.  This
  184. substantially shortens the *.c files and expedites debugging.  For the
  185. curious, this procedure makes an interesting use of the verbatim language;
  186. see typedefs.web.
  187.  
  188.  
  189.